<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Reference</title>
<link rel="stylesheet" href="../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Math Toolkit 4.1.0">
<link rel="up" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">
<link rel="prev" href="facets_intro.html" title="Introduction">
<link rel="next" href="examples.html" title="Examples">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="facets_intro.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_facets.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="examples.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.fp_facets.reference"></a><a class="link" href="reference.html" title="Reference">Reference</a>
</h3></div></div></div>
<h6>
<a name="math_toolkit.fp_facets.reference.h0"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.reference.the_facet_nonfinite_num_put"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.the_facet_nonfinite_num_put">The
        Facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code></a>
      </h6>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
  <span class="keyword">class</span> <span class="identifier">CharType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OutputIterator</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostreambuf_iterator</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">&gt;</span>
        <span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">nonfinite_num_put</span><span class="special">;</span>
</pre>
<p>
        The <code class="computeroutput"><span class="keyword">class</span> <span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span></code> is derived from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_put</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span></code>. Thus it is a facet that formats numbers.
        The first template argument is the character type of the formatted strings,
        usually <code class="computeroutput"><span class="keyword">char</span></code> or <code class="computeroutput"><span class="keyword">wchar_t</span></code>. The second template argument is the
        type of iterator used to write the strings. It is required to be an output
        iterator. Usually the default <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostreambuf_iterator</span></code>
        is used. The public interface of the class consists of a single constructor
        only:
      </p>
<pre class="programlisting"><span class="identifier">nonfinite_num_put</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
</pre>
<p>
        The flags argument (effectively optional because a default of <code class="computeroutput"> <span class="identifier">no_flags</span></code> is provided) is discussed below.
        The class template <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
        is defined in the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">nonfinite_num_facets</span><span class="special">.</span><span class="identifier">hpp</span></code> and lives in the namespace <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>.
      </p>
<p>
        Unlike the C++ Standard facet <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_put</span></code>,
        the facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
        formats <code class="computeroutput"><span class="identifier">infinity</span></code> and <code class="computeroutput"><span class="identifier">NaN</span></code> in a consistent and portable manner.
        It uses the following string representations:
      </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Number
                </p>
              </th>
<th>
                <p>
                  String
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  Positive infinity
                </p>
              </td>
<td>
                <p>
                  inf
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Positive NaN
                </p>
              </td>
<td>
                <p>
                  nan
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative infinity
                </p>
              </td>
<td>
                <p>
                  -inf
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative NaN
                </p>
              </td>
<td>
                <p>
                  -nan
                </p>
              </td>
</tr>
</tbody>
</table></div>
<p>
        The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>,
        <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
        <span class="keyword">double</span></code>. The strings can be in all
        lower case or all upper case. An optional + sign can be used with positive
        numbers. This can be controlled with the <code class="computeroutput"><span class="identifier">uppercase</span></code>,
        <code class="computeroutput"><span class="identifier">lowercase</span></code>, <code class="computeroutput"><span class="identifier">showpos</span></code> and <code class="computeroutput"><span class="identifier">noshowpos</span></code>
        manipulators. Formatting of integers, boolean values and finite floating-point
        numbers is simply delegated to the normal <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_put</span></code>.
      </p>
<h6>
<a name="math_toolkit.fp_facets.reference.h1"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.reference.facet_nonfinite_num_get"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.facet_nonfinite_num_get">Facet
        <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code></a>
      </h6>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">CharType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">InputIterator</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">istreambuf_iterator</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">nonfinite_num_get</span><span class="special">;</span>
</pre>
<p>
        The class <code class="computeroutput"><span class="identifier">nonfinite_num_get</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">InputIterator</span><span class="special">&gt;</span></code> is derived from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">IntputIterator</span><span class="special">&gt;</span></code>. Thus it is a facet that parses strings
        that represent numbers. The first template argument is the character type
        of the strings, usually <code class="computeroutput"><span class="keyword">char</span></code>
        or <code class="computeroutput"><span class="keyword">wchar_t</span></code>. The second template
        argument is the type of iterator used to read the strings. It is required
        to be an input iterator. Usually the default is used. The public interface
        of the class consists of a single constructor only:
      </p>
<pre class="programlisting"><span class="identifier">nonfinite_num_get</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
</pre>
<p>
        The flags argument is discussed below. The <code class="computeroutput"><span class="keyword">class</span>
        <span class="keyword">template</span> <span class="identifier">nonfinite_num_get</span></code>
        is defined in the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">nonfinite_num_facets</span><span class="special">.</span><span class="identifier">hpp</span></code> and lives in the <code class="computeroutput"><span class="keyword">namespace</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>.
      </p>
<p>
        Unlike the facet <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code>, the facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
        parses strings that represent <code class="computeroutput"><span class="identifier">infinity</span></code>
        and <code class="computeroutput"><span class="identifier">NaN</span></code> in a consistent and
        portable manner. It recognizes precisely the string representations specified
        by the C99 standard:
      </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Number
                </p>
              </th>
<th>
                <p>
                  String
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  Positive infinity
                </p>
              </td>
<td>
                <p>
                  inf, infinity
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Positive NaN
                </p>
              </td>
<td>
                <p>
                  nan, nan(...)
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative infinity
                </p>
              </td>
<td>
                <p>
                  -inf, -infinity
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative NaN
                </p>
              </td>
<td>
                <p>
                  -nan, -nan(...)
                </p>
              </td>
</tr>
</tbody>
</table></div>
<p>
        The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>,
        <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
        <span class="keyword">double</span></code>. The facet is case-insensitive.
        An optional + sign can be used with positive numbers. The dots in nan(...)
        stand for an arbitrary string usually containing the <span class="emphasis"><em>NaN payload</em></span>.
        Parsing of strings that represent integers, boolean values and finite floating-point
        numbers is delegated to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code>.
      </p>
<p>
        When the facet parses a string that represents <code class="computeroutput"><span class="identifier">infinity</span></code>
        on a platform that lacks infinity, then the fail bit of the stream is set.
      </p>
<p>
        When the facet parses a string that represents <code class="computeroutput"><span class="identifier">NaN</span></code>
        on a platform that lacks NaN, then the fail bit of the stream is set.
      </p>
<h5>
<a name="math_toolkit.fp_facets.reference.h2"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.reference.flags"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.flags">Flags</a>
      </h5>
<p>
        The constructors for <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
        and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> take
        an optional bit flags argument. There are four different bit flags:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            legacy
          </li>
<li class="listitem">
            signed_zero
          </li>
<li class="listitem">
            trap_infinity
          </li>
<li class="listitem">
            trap_nan
          </li>
</ul></div>
<p>
        The flags can be combined with the OR <code class="computeroutput"><span class="keyword">operator</span><span class="special">|</span></code>.
      </p>
<p>
        The flags are defined in the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">nonfinite_num_facets</span><span class="special">.</span><span class="identifier">hpp</span></code> and live in the <code class="computeroutput"><span class="keyword">namespace</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>.
      </p>
<h6>
<a name="math_toolkit.fp_facets.reference.h3"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.reference.legacy"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.legacy">legacy</a>
      </h6>
<p>
        The legacy flag has no effect with the output facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>.
      </p>
<p>
        If the legacy flag is used with the <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
        input facet, then the facet will recognize all the following string representations
        of <code class="computeroutput"><span class="identifier">infinity</span></code> and <code class="computeroutput"><span class="identifier">NaN</span></code>:
      </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Number
                </p>
              </th>
<th>
                <p>
                  String
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  Positive infinity
                </p>
              </td>
<td>
                <p>
                  inf, infinity, one#inf
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Positive NaN
                </p>
              </td>
<td>
                <p>
                  nan, nan(...), nanq, nans, qnan, snan, one#ind, one#qnan, one#snan
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative infinity
                </p>
              </td>
<td>
                <p>
                  -inf, -infinity, -one#inf
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  Negative NaN
                </p>
              </td>
<td>
                <p>
                  -nan, -nan(...), -nanq, -nans, -qnan, -snan, -one#ind, - one#qnan,
                  -one#snan
                </p>
              </td>
</tr>
</tbody>
</table></div>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>,
            <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>.
          </li>
<li class="listitem">
            The facet is case-insensitive.
          </li>
<li class="listitem">
            An optional <code class="computeroutput"><span class="special">+</span></code> sign can be
            used with the positive values.
          </li>
<li class="listitem">
            The dots in <code class="computeroutput"><span class="identifier">nan</span><span class="special">(...)</span></code>
            stand for an arbitrary string.
          </li>
<li class="listitem">
            <code class="computeroutput"><span class="identifier">one</span></code> stands for any string
            that <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code> parses as the number <code class="computeroutput"><span class="number">1</span></code>, typically "1.#INF", "1.QNAN"
            but also "000001.#INF"...
          </li>
</ul></div>
<p>
        The list includes a number of non-standard string representations of infinity
        and NaN that are used by various existing implementations of the C++ standard
        library, and also string representations used by other programming languages.
      </p>
<h6>
<a name="math_toolkit.fp_facets.reference.h4"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.reference.signed_zero"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.signed_zero">signed_zero</a>
      </h6>
<p>
        If the <code class="computeroutput"><span class="identifier">signed_zero</span></code> flag is
        used with <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>,
        then the facet will always distinguish between positive and negative zero.
        It will format positive zero as "0" or "+0" and negative
        zero as "-0". The string representation of positive zero can be
        controlled with the <code class="computeroutput"><span class="identifier">showpos</span></code>
        and <code class="computeroutput"><span class="identifier">noshowpos</span></code> manipulators.
      </p>
<p>
        The <code class="computeroutput"><span class="identifier">signed_zero</span> <span class="identifier">flag</span></code>
        has no effect with the input facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>.
        The input facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
        always parses "0" and "+0" as positive zero and "-0"
        as negative zero, as do most implementations of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code>.
      </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
          If the <code class="computeroutput"><span class="identifier">signed_zero</span></code> flag
          is not set (the default), then a negative zero value will be displayed
          on output in whatever way the platform normally handles it. For most platforms,
          this it will format positive zero as "0" or "+0" and
          negative zero as "-0". But setting the <code class="computeroutput"><span class="identifier">signed_zero</span></code>
          flag may be more portable.
        </p></td></tr>
</table></div>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
          A negative zero value can be portably produced using the changesign function
          <code class="computeroutput"><span class="special">(</span><span class="identifier">changesign</span><span class="special">)(</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">ValType</span><span class="special">&gt;(</span><span class="number">0</span><span class="special">))</span></code>
          where <code class="computeroutput"><span class="identifier">ValType</span></code> is <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code>
          or <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>,
          or a User-Defined floating-point type (UDT) provided that this UDT has
          a sign and that the changesign function is implemented.
        </p></td></tr>
</table></div>
<h6>
<a name="math_toolkit.fp_facets.reference.h5"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.reference.trap_infinity"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.trap_infinity">trap_infinity</a>
      </h6>
<p>
        If the <code class="computeroutput"><span class="identifier">trap_infinity</span></code> flag
        is used with <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>,
        then the facet will throw an exception of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">failure</span></code>
        when an attempt is made to format positive or negative infinity. If the facet
        is called from a stream insertion operator, then the stream will catch that
        exception and set either its <code class="computeroutput"><span class="identifier">fail</span>
        <span class="identifier">bit</span></code> or its <code class="computeroutput"><span class="identifier">bad</span>
        <span class="identifier">bit</span></code>. Which bit is set is platform
        dependent.
      </p>
<p>
        If the <code class="computeroutput"><span class="identifier">trap_infinity</span></code> flag
        is used with <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>,
        then the facet will set the <code class="computeroutput"><span class="identifier">fail</span>
        <span class="identifier">bit</span></code> of the stream when an attempt
        is made to parse a string that represents positive or negative infinity.
      </p>
<p>
        (See Design Rationale below for a discussion of this inconsistency.)
      </p>
<h6>
<a name="math_toolkit.fp_facets.reference.h6"></a>
        <span class="phrase"><a name="math_toolkit.fp_facets.reference.trap_nan"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.trap_nan">trap_nan</a>
      </h6>
<p>
        Same as <code class="computeroutput"><span class="identifier">trap_infinity</span></code>, but
        positive and negative NaN are trapped instead.
      </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2006-2021 Nikhar Agrawal, Anton Bikineev, Matthew Borland,
      Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert Holin, Bruno
      Lalande, John Maddock, Evan Miller, Jeremy Murphy, Matthew Pulver, Johan Råde,
      Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, Daryle
      Walker and Xiaogang Zhang<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="facets_intro.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_facets.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="examples.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
